package com.insight.export.generator;

import com.insight.common.enums.ExportFormat;
import com.insight.entity.DataSource;
import com.insight.entity.MetadataTable;

import java.io.IOException;
import java.nio.file.Path;
import java.util.List;

/**
 * T083: 数据字典导出生成器接口 (策略模式)
 * <p>
 * 定义统一的数据字典导出接口,支持多种导出格式(Markdown/HTML/Excel/PDF).
 * 使用策略模式实现,每种格式对应一个具体实现类.
 * </p>
 *
 * <p><b>设计模式</b>: Strategy Pattern</p>
 * <ul>
 *   <li>Strategy Interface: ExportGenerator</li>
 *   <li>Concrete Strategies: MarkdownExportGenerator, HtmlExportGenerator, ExcelExportGenerator, PdfExportGenerator</li>
 *   <li>Context: ExportService (使用工厂方法选择具体策略)</li>
 * </ul>
 *
 * <p><b>使用示例</b>:</p>
 * <pre>{@code
 * ExportGenerator generator = exportGeneratorFactory.getGenerator(ExportFormat.MARKDOWN);
 * Path exportedFile = generator.generate(dataSource, tables, outputDir);
 * }</pre>
 *
 * @author Insight Team
 */
public interface ExportGenerator {

    /**
     * 生成数据字典文件
     *
     * @param dataSource 数据源信息
     * @param tables     表元数据列表
     * @param outputDir  输出目录路径
     * @return 生成的文件路径
     * @throws IOException              文件写入失败
     * @throws IllegalArgumentException 参数验证失败
     */
    Path generate(DataSource dataSource, List<MetadataTable> tables, Path outputDir) throws IOException;

    /**
     * 获取当前生成器支持的导出格式
     *
     * @return 导出格式枚举
     */
    ExportFormat getSupportedFormat();

    /**
     * 获取导出文件扩展名 (不含点号)
     * <p>
     * 示例: "md", "html", "xlsx", "pdf"
     * </p>
     *
     * @return 文件扩展名
     */
    String getFileExtension();
}
